Bicycle For Your Mind
Writing (Better) Markdown in Sublime Text 3
If you are using Sublime Text 3 you need to get package control installed. Go here. Follow the instructions and get Package Control installed. Have you installed it? Good.
Sublime Text 3 provides a Markdown package by default. It is nice but lacking in features. We are going to use the community contributed packages and ignore the default markdown package. These are the packages we are going to install to make Sublime Text 3 a fantastic markdown editor.
- The Markdown Editing package.
- The typewriter package.
- The Github Markdown Snippets package.
- Themes for Markdown Writing.
The MarkdownEditing Package
Read about it here. Install it through Package Control.
What does this do? Read the readme.md file in the package and you will get all the details. I am going to highlight some of the features which makes this package useful to me.
Flavors of Markdown supported
The MarkdownEditing package brings support for three flavors of markdown to Sublime Text 3: Standard Markdown, Github Flavored Markdown(GFM) and MultiMarkdown. I have all markdown files assigned to Github Flavored Markdown and that lets me use tables, footnotes and tasks.
Features which I find useful
This is going to be a long list. I am fond of this plugin:
- Asterisks and underscores are auto paired and will wrap selected text. So, it is easy to apply bold and italic just by typing one or two asterisks. When you are wanting an italic, just type an asterisk and the cursor gets surrounded by two asterisks. Type another one and you are in markup for bold. I don’t use that much though, I press ⌘ + ⌥ + B. That gives me four asterisks with the cursor in the middle. I type in what I need bolded, then press ⌃ + E to get to the end of the markup and get on with my writing.
- Backticks, the markup for code, are paired.
- Lists are handled well.
- At the end of a list item, pressing Return will insert a new list item. If it is an ordered list, you will get a new list item with the incremental number already in place.
- Pressing Tab on the blank list item will indent it and switch the list bullet to another one (Order is
*,-,+in a cycle). Much like this list is doing. - Pressing ⇧ + Tab on a blank list item will unindent it, and switch back to the list marker which was used in the previous level of the list.
- You can disable automatic bullet switching or choose which bullets to be used, in the settings file.
- If a list item contains a GFM task, pressing Return at the end of the line, will continue with a new blank task.
- At the end of a blockquote line, pressing Return will extend the blockquote.
- More interestingly, selecting some text and pressing > will convert the content to a blockquote. You don’t have to select the whole paragraph, any portion of it selected will turn the paragraph into a blockquote.
- If you select a word and type [, the word is going to be surrounded by square brackets and the cursor will be placed at the end of the right square bracket. Type ( and the right parenthesis is going to be added, with the cursor in the middle. Paste or type in the URL, and you now have a link completed.
- ~ wraps selected text with ~~ (strikethrough).
- Select a line. Type # and it is preceded by a #. Type as many as the header level needs. Move on.
Keyboard Commands
I am going to talk about some of the keyboard commands that are useful to me. However, I made a change to the default assignments. By default, ⌘ + ⌥ + V pastes the contents of the clipboard as an inline link on selected text. Didn’t work for me. It clashed with the default paste command, and I changed it to ⌘ + ⌥ + L. Works like a charm now.
You change the default keyboard commands by finding the keyboard command in the Plugins default Keybindings file. SublimeText>Preferences>Package Settings>MarkdownEditing>Key Bindings - Default file. In this case, it was:
{ "keys": ["super+alt+v"], "command": "paste_as_link", "context":
[
{ "key": "selector", "operator": "equal", "operand": "text.html.markdown", "match_all": true }
]
}I changed the “super+alt+v” to “super+alt+l”. Copied the whole section into the SublimeText>Preferences>Package Settings>MarkdownEditing>Key Bindings - User file. Now when I select a section and press ⌘ + ⌥ + L, it surrounds the selected text in square brackets and then puts the URL in the clipboard in parenthesis after the end of the square brackets, turning the selected text into a properly formatted Markdown inline link. Very useful.
| Keyboard command | Effect |
|---|---|
| ⌘ + ⌥ + V (changed to ⌘ + ⌥ + L) | Pastes the contents of the clipboard as an inline link on selected text |
| ⌘ + ⌥ + R | Pastes the contents of the clipboard as a reference link |
| ⌘ + ⌥ + K | Inserts a standard inline link |
| ⌘ + ⌥ + B & ⌘ + ⌥ + I | These are for bold and italic formatting. They are a toggle, you can turn them off/on. |
| ⌘ + ⌃ + 1…6 | These will add the heading markup. Number denotes the number of hashes. |
Configuration
The default flavor of Markdown the plugin supports is Github Flavored Markdown. If you want to change that, open a markdown file and select your flavor from the menu View > Syntax > Open all with current extension as.
Depending on your choice of flavor, you can look at the default settings files here:
Packages/MarkdownEditing/Markdown.sublime-settings [GitHub flavored Markdown]
Packages/MarkdownEditing/Markdown (Standard).sublime-settings
Packages/MarkdownEditing/MultiMarkdown.sublime-settingsYou can override any of the default settings in the appropriate user settings file. Each flavor has a different settings file.
Bold and italic markers are configured through ST shell variables. You can choose Preferences > Package Settings > Markdown Editing > Bold and Italic Settings - Default to see the default settings file. In order to override it, copy & paste its content into the user settings file Preferences > Package Settings > Markdown Editing > Bold and Italic Settings - User from the menu and make your edits. Should be fairly uncomplicated.
The package comes with a selection of themes and you can use them if you want. I am going to cover themes in greater detail a little later in the article.
The Typewriter Package
The Typewriter package does two things:
- Typewriter scrolling: Saves you from staring at the bottom of the screen when you are typing a document. Keeps the current line at the middle of the screen and it makes writing a better experience.
- Typewriter typing: A travel back in time. This plugin setting moves your cursor to the end of the file and disables mouse clicks and all commands that move the cursor and/or select text – leaving you only with letters, numbers, symbols, Backspace, Delete and Enter.
You can enable the Typewriter Scrolling setting by putting this in your Markdown Distraction Free User file:
"typewriter_mode_scrolling" : true,The Typewriter Typing mode is a toggle. Use the ⌘ + ⇧ + P command and type Typewriter. It will show up and you can toggle it on and off by choosing it. I don’t use this much. It drives me batty.
For the best results in Typewriter Scrolling mode you should set add this to your distraction free preference file:
"scroll_past_end": trueThe Github Markdown Snippets package
This is an interesting snippets package. You type the trigger and hit Tab and the snippet expands. These are the snippets available:
| List of Tab Triggers | Markdown Equivalent |
|---|---|
| mh1-mh6 | Heading1-6 |
| mb | Bold |
| mi | Italic |
| mbq | Blockquote |
| mstrike | Strikeout |
| mhr | Horizontal ruler |
| mcode | Inline Code |
| mpre | Code Block with language based highlighting |
| mol | Ordered List |
| mul | Unordered List |
| mtable | Table |
Themes for Markdown writing
The MarkdownEditing Package ships with a few themes. Here are a few more which I like:
- This one is from Wes Bos. It is called Theme - Cobalt2. It is a dark theme which supports all of Markdown. While I am on the subject of Wes Bos, he has a book on Sublime Text called Sublime Text Power User. If you want to use this editor to its full potential, you have to get the book and the videos which come along with it.
- The Material Theme from Mattia Astorino. I particularly like the lighter theme.
- The Github Color Theme by Alexander Ekdahl.
- The Preap Theme by equinusocio.
- The Predawn Theme by Jamie Wilson.
- The Writing Color Scheme by kmisiunas.
There are about 110 themes posted on Package Control. Before installing any of them, it is a good idea to download the zipped file from the github repository, open the theme file in Sublime Text 3 and search for the word mark. If the theme supports markdown you are going to find a lot of occurrences of that word, more than 15, at least. If it doesn’t, it is going to be a lot fewer. Fewer occurrences of the word denotes that the theme doesn’t really support markdown. You can tweak those themes to support markdown, but they will not be adequate without the tweaking. I am going to deal with how to tweak a theme to support markdown in a later article.
Conclusion
I use Marked 2 app for previewing the markdown files. It is one of mad scientist Brett Terpstra’s creations. It does a lot of things, and does them well. I wouldn’t use markdown without it. Get yourself a copy.
You can find my Sublime Text 3 setting files here.
Acknowledgment
I must express my admiration of the readme.md file which accompanies the MarkdownEditing plugin. I have learned from it, and have used it to write this article. Thank you Ali Ayas for making my life better.
Update 2015-12-23
I have been using the Material Theme, and the color scheme: Material-Theme-Darker.sublime-theme. Together they provide a beautiful environment to write in. Very impressive.
Update 2015-12-01
There is a new color scheme called Mandarin Peacock Color Scheme - Packages - Package Control which got posted to packagecontrol.io. It is a dark scheme which supports all of the Markdown tags. Very nice.
macosxguru